DisposeThread

DisposeThread
Header:	Threads.h		Carbon status:	Supported

Deletes a thread when it finishes executing.

OSErr DisposeThread (
    ThreadID threadToDump, 
    void *threadResult, 
    Boolean recycleThread
);

threadToDump: The thread ID of the thread to delete.
threadResult: A pointer to the threadís result. The DisposeThread function places this result to an address which you originally specify with the threadResult parameter of the NewThread function when you create or allocate the thread. Pass a value of NULL if you are not interested in obtaining a function result.
recycleThread: A Boolean value that specifies whether to return the thread to the allocation pool or to remove it entirely. Specify False to dispose of the thread entirely and True to return it to the thread pool.

function result: A result code.

DISCUSSION

When a thread finishes executing, the Thread Manager automatically calls DisposeThread to delete it. Therefore, the only reason for you to explicitly call DisposeThread is to recycle a terminating thread. To do so, set the recycleThread parameter to True. The Thread Manager clears out the threadís internal data structure, resets it, and puts the thread in the thread pool where it can be used again as necessary.

The DisposeThread function sets the threadResult parameter to the threadís function result. You allocate the storage for the thread result when you create or allocate a thread with the NewThread function.

You cannot explicitly dispose of the main application thread. If you attempt to do so, DisposeThread returns the threadProtocolErr result code.

When your application terminates, the Thread Manager calls DisposeThread to terminate any active threads. It terminates stopped and ready threads first but in no special order. It terminates the currently running thread last. This thread should always be the main application thread.

To install a callback function to do special cleanup when a thread terminates, use the SetThreadTerminator function.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when ThreadsLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by ThreadsLib 1.0 and later.